home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / fastbak.arc / SPKR.DOC < prev    next >
Text File  |  1986-05-09  |  10KB  |  266 lines
  1.                                V1.01 22 Mar 1986
  2.  
  3.                            SPK Device Documentation
  4.                            ------------------------
  5.  
  6.         Purpose
  7.         -------
  8.  
  9.         SPKR.SYS is a DOS installable device driver that allows any
  10.         application to produce arbitrary pitch/duration sounds on the
  11.         PC's speaker.  SPKR requires DOS 2.0 or later and an IBM PC
  12.         compatible machine.
  13.  
  14.  
  15.         Installation
  16.         ------------
  17.  
  18.         To install SPKR, follow two steps: place the file SPKR.SYS in
  19.         the root directory of your boot diskette or hard disk, and
  20.         modify the CONFIG.SYS file to include the statement
  21.         "device=spkr.sys".
  22.  
  23.         In case you are not familiar with CONFIG.SYS: this is a small
  24.         text file that DOS reads when booting.  It contains various
  25.         pieces of information that DOS and other programs can use when
  26.         setting themselves up.  Look in the root directory of your boot
  27.         disk for the file CONFIG.SYS.  If no such file exists, just
  28.         type:
  29.  
  30.                 copy con \config.sys<Enter>
  31.                 device=spkr.sys<Enter>
  32.  
  33.         Then press Ctrl-Z (you'll see "^Z") and <Enter>, and you're
  34.         done.
  35.  
  36.         If you already have a CONFIG.SYS file (which is likely), you
  37.         must edit it to include the statement "device=spkr.sys".  Do
  38.         this using your text editor or word processor in text mode (or
  39.         Edlin, heaven forbid).  Retain all existing information, and add
  40.         the new line.
  41.  
  42.         Now reboot your machine.  If all goes well, it will boot as
  43.         usual.  There will be no immediate indication that anything has
  44.         happened, except that you will see SPKR's logo and copyright.
  45.  
  46.         If you have a hard disk and wish to place SPKR.SYS in a
  47.         directory other than the root, you may do so.  Just alter the
  48.         CONFIG.SYS statement to reflect the full path where SPKR.SYS can
  49.         be found.
  50.  
  51.  
  52.         Using the SPK device
  53.         --------------------
  54.  
  55.         When DOS finds the "device=spkr.sys" line in config.sys, it
  56.         loads and installs the SPKR.SYS program as a virtual device.
  57.         What this means, practically speaking, is that there is now a
  58.         new "device" attached to your PC. You already have several
  59.         devices installed: CON, PRN, COM1 and COM2, AUX, your disk
  60.         drives, and possibly a RAM (or virtual) disk if you have
  61.         installed VDISK.SYS or another disk emulator.
  62.  
  63.         The new device is known to DOS by the name "SPK" (note: this is
  64.         NOT "SPKR", it's "SPK", no R).  Like other output devices, you
  65.         can write (send information) to the device.  SPK is an "output
  66.         only" device like a printer: you can send information to it, but
  67.         you cannot receive information from it.
  68.  
  69.         To use SPK, you must send a series of frequencies and durations
  70.         to the SPK device.  Durations are measured in PC clock ticks,
  71.         which occur about 18.2 times per second; thus, for example, a
  72.         duration of 18 is about one second.
  73.  
  74.         The syntax of data sent to SPK is:
  75.  
  76.             {<frequency>,<duration>;}<CR>
  77.  
  78.         The {} means that you can send one or more sequences of
  79.         frequency and duration to the device.  The <CR> is a carriage
  80.         return, ASCII code 13.
  81.  
  82.         Here are two examples of valid sequences for SPK:
  83.  
  84.             1000,18;<CR>
  85.                 Make a 1000 cps tone for one second
  86.  
  87.             1000,18;2000,36;<CR>
  88.                 Make a 1000 cps tone for one second, then a
  89.                 2000 cps tone for two seconds.
  90.  
  91.         A frequency of 0 is a "rest": no sound will be issued for the
  92.         specified duration.
  93.  
  94.         SPK's sounds are played in background.  That is, control is
  95.         returned immediately to the program that sends data to SPK (the
  96.         "foreground" program).  The sounds will be played while
  97.         foreground execution continues.
  98.  
  99.         There are many ways to send information to SPK.  The simplest is
  100.         to do it right from the keyboard, at the DOS prompt:
  101.  
  102.                 copy con spk<Enter>
  103.                 1000,18<Enter>
  104.                 ^Z<Enter>
  105.  
  106.         The "copy con spk" command tells DOS that you want to copy input
  107.         from the console input (the keyboard) to the SPK device (the
  108.         speaker).  The keyboard input "1000,18<Enter>" is copied to the
  109.         SPK device when you hit the Ctrl-Z (end of copy) and <Enter>
  110.         (execute) keys.
  111.  
  112. FRB!... In batch files use:  ECHO 1500,3;3333,3;>SPK
  113.  
  114.         Another way to write to the device is to copy a small textfile
  115.         to SPK.  For example, type
  116.  
  117.                 copy con spkdemo.txt<Enter>
  118.                 1000,10;2000,5;<Enter>
  119.                 ^Z<Enter>
  120.  
  121.         You should now have a small textfile called SPKDEMO, the
  122.         contents of which are "1000,10;2000,5".  To send it to the
  123.         speaker (sounding two tones), just type
  124.  
  125.                 copy spkdemo.txt spk
  126.                         or
  127.                 type spkdemo.txt > spk
  128.  
  129.         You could, of course, put either of those two commands in a DOS
  130.         batch file.
  131.  
  132.         It is also possible to send data to SPK from high level
  133.         languages or from assembler programs.  The following examples
  134.         lack error checking for conciseness; you should add checks to
  135.         ensure that the SPK device is installed (typically by trapping
  136.         for an error in opening the file "SPK").
  137.  
  138.         In BASIC:
  139.  
  140.                 10 FREQ=1000: DUR=10: GOSUB 1000
  141.                 20 END
  142.                 1000 'Sound speaker at FREQ for DUR
  143.                 1010 OPEN "SPK" FOR OUTPUT AS #1
  144.                 1020 PRINT #1, FREQ;",";DUR;";"
  145.                 1030 CLOSE 1
  146.                 1040 RETURN
  147.  
  148.                 This is a bit superfluous in BASIC, however, since
  149.                 BASIC's "SOUND" statement provides essentially the
  150.                 same function.  The main difference is that SPK's
  151.                 sounds play in background.
  152.  
  153.  
  154.         In C:
  155.  
  156.                 spkr (freq, dur)
  157.                 unsigned freq, dur;
  158.                 {
  159.                 FILE *spk, *fopen();
  160.  
  161.                         spk = fopen("SPK","w");
  162.                         fprintf (spk, "%u,%u;\n", freq, dur);
  163.                         fclose(spk);
  164.                 }
  165.  
  166.  
  167.         In Turbo Pascal:
  168.  
  169.                 Procedure Spkr (Freq, Dur: Integer);
  170.                 Var f: Text;
  171.                 Begin
  172.                     Assign (f, 'SPK');
  173.                     Rewrite (f);
  174.                     WriteLn (f, Freq, ',', Dur, ';');
  175.                     Close (f)
  176.                 End;
  177.  
  178.  
  179.         SPK and PCED
  180.         ------------
  181.  
  182.         If you are using the PCED command interface, you can send data
  183.         to the speaker using the SEND user-installed command:
  184.  
  185.             SEND SPK 1000,10;2000,5;\13
  186.  
  187.  
  188.         Limits
  189.         ------
  190.  
  191.         Valid frequencies are 0 (rest), and 20 through 30000.  Only your
  192.         dog will hear frequencies above approximately 15000 cps.
  193.  
  194.         Valid durations are 1 through 65535 (about an hour).
  195.  
  196.         All numeric input is treated modulo 65536; that is, if you
  197.         specify a number larger than 65536, SPKR will actually use the
  198.         remainder of your input divided by 65536.
  199.  
  200.         If your input is outside of the valid range, it will be
  201.         converted to the highest or lowest value, as appropriate.  Thus,
  202.         e.g., a frequency of 35000 will be changed to 30000.
  203.  
  204.         SPK can store up to 128 frequency/duration pairs.  Additional
  205.         sounds will be discarded.
  206.  
  207.         There is a limit of 255 characters per input line to SPKR (i.e.,
  208.         maximum of 255 characters sent before a carriage return).  Data
  209.         beyond 255 characters will be discarded.
  210.  
  211.         Any data sent to SPK other that '0' through '9', ';', ',', and
  212.         carriage returns are ignored.
  213.  
  214.         Invalid frequency/duration pairs are discarded.
  215.  
  216.  
  217.         Frequency Chart
  218.         ---------------
  219.  
  220.         Here is an approximate frequency chart:
  221.  
  222.             A  440           E 659
  223.             B  494           F 698
  224.             C  523           G 784
  225.             D  587
  226.  
  227.         The 523 Hz "C" is middle C.  To increase a note by one octave,
  228.         double the frequency; to decrease by one octave, halve it.
  229.  
  230.  
  231.  
  232.         Copyright/License/Warranty
  233.         --------------------------
  234.  
  235.         This document and the current version of the program file
  236.         SPKR.SYS ("the software") are copyrighted by the author.  The
  237.         copyright owner hereby licenses you to: use the software; make
  238.         as many copies of the program and documentation as you wish;
  239.         give such copies to anyone; and distribute the software and
  240.         documentation via electronic means.
  241.  
  242.         However, you are specifically prohibited from charging, or
  243.         requesting donations, for any such copies, however made.  An
  244.         exception is granted to recognized not-for-profit user's
  245.         groups, which are authorized to charge a small fee (not to
  246.         exceed $7) for materials, handling, postage, and general
  247.         overhead.  NO FOR-PROFIT ORGANIZATION IS AUTHORIZED TO CHARGE
  248.         ANY AMOUNT FOR DISTRIBUTION OF COPIES OF THE SOFTWARE OR
  249.         DOCUMENTATION.
  250.  
  251.         No copy of the software may be distributed or given away without
  252.         this document; and this notice must not be removed.
  253.  
  254.         There is no warranty of any kind, and the copyright owner is not
  255.         liable for damages of any kind.  By using the software, you
  256.         agree to this.
  257.  
  258.         The software and documentation are:
  259.  
  260.                              Copyright (c) 1986 by
  261.                             Christopher J. Dunford
  262.                            10057-2 Windstream Drive
  263.                            Columbia, Maryland 21044
  264.                                 (301) 992-9371
  265.                              CompuServe 76703,2002
  266.